.Dd 02/23/22
.Dt genie 8
.Os Linux
.Sh NAME
.Nm genie
.Nd start up, enter into, or shut down a systemd "bottle" under Windows
Subsystem for Linux.
.Sh SYNOPSIS
.Nm
.Op -h
.Op -V
.Op -v
.Op -a
.Ar user
.Op -i
.Op -b
.Op -r
.Op -s
.Op -l
.Op -c
.Ar command...
.Sh DESCRIPTION
.Nm
provides a means of running
.Xr systemd 1
as pid 1, with all the trimmings, within a WSL 2 distribution. It does this by
creating a pid and mount namespace, the eponymous poor-man's container
"bottle", starting up
.Xr systemd 1
within the bottle, and providing helpful shortcuts to start, enter, run
commands within, and shut down the bottle.
.Pp
.Bl -tag -width "-c ..., --command ..."
.It Fl h, -help
Prints a short help text and exits.
.It Fl V, -version
Prints the installed genie version and exits.
.It Fl v, -verbose
Causes any other command to print the details of the operations it is
performing as it goes along. Useful mostly for debugging.
.It Fl a, -as-user
Permits a user to be specified (by name) to execute as when using the -c/--command
or -s/--shell commands.
.It Fl i, -initialize
Sets up the bottle and
.Xr systemd 1
if they are not already initialized, and then exists. This is intended, for
use, for example, if you wish to run services without needing a shell, or to
preinitialize the bottle to avoid startup delays later. This latter can be used
with Task Scheduler, to be run on Windows logon.
.It Fl s, -shell
Sets up the bottle and
.Xr systemd 1
if they are not already initialized, and then runs your login shell within the
bottle. It is intended as the standard way to start a shell within a
distribution with
.Nm
installed.
.Pp
This follows login semantics, and as such does not preserve the current working
directory.
.It Fl l, -login
Sets up the bottle and
.Xr systemd 1
if they are not already initialized, and then opens a login session within the
bottle. This permits you to log in to the WSL distribution as any user. The
login prompt will return when you log out; to terminate the session, press ^]
three times within one second.
.Pp
This follows login semantics, and as such does not preserve the current working
directory.
.It Fl c, -command
Sets up the bottle and
.Xr systemd 1
if they are not already initialized, and then runs the specified command within the
bottle. It is intended as the standard way to run arbitrary commands within a
distribution with
.Nm
installed.
.Pp
Unlike the other options, this preserves the current working directory.
.It Fl u, -shutdown
Shuts down
.Xr systemd 1
cleanly and exits the bottle. This uses the
.Ar systemctl poweroff
command to simulate a normal Linux system shutting down. It is suggested that
this be used before shutting down the Windows machine or restarting the Linux
distribution to ensure a clean shutdown of systemd services.
.Pp
While not compulsory, it is recommended that you shut down and restart the WSL
distribution before using
.Nm
again after you have used
.Ar genie -u.
See BUGS, below, for more details.
.It Fl r, -is-running
Checks whether
.Nm
and an associated
.Xr systemd 1
are currently running. Returns
.Ar running
and exit code 0 if so. Other possible return values include
.Ar stopped
and exit code 1 if they are not;
.Ar starting
and exit code 2 and
.Ar stopping
and exit code 3 if they are currently transitioning between states;
.Ar running (systemd errors)
and exit code 4 if there is a problem with systemd services; and
.Ar unknown
and exit code 5 otherwise.
.It Fl b -is-in-bottle
Checks whether the current command is executing inside the bottle. Returns
.Ar inside
and exit code 0 if so; returns
.Ar outside
and exit code 1 if not. If no bottle exists, returns
.Ar no-bottle
and exit code 2.
.El
.Sh ENVIRONMENT
.Bl -tag -width "INSIDE_GENIE"
.It Ev INSIDE_GENIE
INSIDE_GENIE should not be set by the user.
.Nm
sets INSIDE_GENIE to the string "yes", such that user scripts can detect its
presence to determine whether or not they are running inside the bottle.
.El
.Sh EXIT STATUS
Other than the special exit codes listed under the
.Ar -b
and
.Ar -r
options above,
.Nm
maintains a policy of returning zero on success, and non-zero when an error
occurs.
.Sh FILES
.Bl -tag -width "/run/genie.systemd.pid" -compact
.It Pa /etc/genie.ini
Configuration file for
.Nm
This contains the secure path which
.Nm
uses when searching for executables used internally. In a typical Linux
installation, there should be no need to modify this. Other settings affecting
.Nm
behavior include
.Ar update-hostname
and
.Ar update-hostname-suffix
which control whether
.Nm updates the hostname within the bottle, or not (defaults on);
.Ar clone-path,
which controls whether
.Nm
clones the outside-bottle PATH to inside the bottle (defaults off);
.Ar clone-env,
which lists the environment variables to be copied from outside to inside the
bottle;
.Ar systemd-timeout,
which sets the length of time in seconds
.Nm
will wait for
.Xr systemd 1
to reach the running state;
.Ar resolved-stub,
which determines whether or not
.Nm
will create the symlink needed to run
.Xr systemd-resolved 8
in stub mode; and
.Ar target-warning
which can be used to disable the warning if the default target is set to
something other than
.Ar multi-user.target.
.It Pa /run/genie.env
Contains certain environment variables required for proper functioning copied
from outside the bottle, used internally by
.Nm
to restore them within the bottle.
.It Pa /run/genie.hostname
Contains the modified hostname used by the WSL distribution (see NOTES). This
file is bind mounted over
.Ar /etc/hostname
when the bottle is started up, and unbound at shutdown.
.It Pa /run/genie.path
Contains the system PATH copied from outside the bottle, used internally by
.Nm
to restore the directories therein within the bottle.
.It Pa /run/genie.systemd.pid
Contains the external PID of the systemd(1) instance created by
.Nm
Not used by
.Nm
itself; this PID is recorded as a convenience for the user. No analogous file
exists containing the internal PID, for obvious reasons.
.El
.Sh NOTES
.Nm
can only be used within a WSL 2 distribution, since
.Xr systemd 1
can only be run within a WSL 2 distribution. WSL 1 does not implement the
system calls required to support it.
.Pp
.Nm
serves no purpose on Linux running outside of the WSL environment, or within
other containers. Its behavior if run in such environments is undefined.
.Pp
When setting up the bottle:
.Pp
If configured, the hostname of the WSL session is changed from the default (the
hostname of the Windows machine) by suffixing -wsl, to distinguish it from the
Windows host.
.Pp
The bottle uses pid and mount namespaces. Other namespaces remain shared with
the parent (outside bottle). The mount propagation flag is set to shared.
.Sh SEE ALSO
.Xr systemctl 1 ,
.Xr systemd 1 ,
.Xr bootup 7 ,
.Xr namespaces 7 ,
.Xr systemd-machined 8 ,
.Xr systemd-resolved 8
.Sh BUGS
.Nm
is not idempotent; i.e., it is possible that changes made by
.Nm
or by
.Xr systemd 1
inside the bottle will not be perfectly reverted when the bottle is shut down
with
.Ar genie -u.
As such, it is recommended that you terminate the entire wsl session with
.Ar wsl -t
or
.Ar wsl --shutdown
in between stopping and restarting the bottle, or errors may occur.
.Pp
If you feel you have found a bug in \fBgenie\fR, please submit a bug report at
.Ar http://github.com/arkane-systems/genie/issues
